@link-assistant/web-capture 1.7.26 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/web-capture
 
+## 1.8.0
+
+### Minor Changes
+
+- 09f83f3: Pin the default image-mode contract and route every capture path through a single image-handling chokepoint (`applyImageMode`), so the same flag behaves identically regardless of capture method (browser vs API, CLI vs server) — issue #112. Default `--format markdown` now references images by their direct remote URL (no `images/` folder, no inline base64); inline base64 (which has no remote URL to restore) is stripped to a visible placeholder with a warning instead of being silently kept as a multi-megabyte blob. `--embed-images` keeps base64 inline for a self-contained file. The new `--extract-images[=DIR]` flag extracts inline base64 **and** downloads remote images into `DIR/images/`, rewriting the markdown to reference the local files; on download failure the original remote URL is restored so references never break. `--keep-original-links` remains a back-compat alias for the default behavior.
+
+## 1.7.27
+
+### Patch Changes
+
+- 9cbb4c7: Pin the default `--format archive` layout contract so the zip always contains exactly `document.md` + `document.html` + `images/` (issue #113). The markdown-format archive endpoint previously bundled only `document.md` and `images/`, omitting the reference `document.html`; it now includes it on every path. Adds a reusable `buildArchiveFromHtml(html, baseUrl)` helper and an integration test that pins the layout so a future refactor cannot regress it.
+
 ## 1.7.26
 
 ### Patch Changes

package/README.md

@@ -73,11 +73,17 @@ web-capture https://example.com --archive
 web-capture https://example.com --archive zip -o site.zip
 web-capture https://example.com --archive tar.gz -o site.tar.gz
 
-# Keep images inline as base64 (opt-in)
+# Default markdown keeps remote image URLs as direct links
+web-capture https://example.com -o page.md
+
+# Keep images inline as base64 (self-contained file, opt-in)
 web-capture https://example.com --embed-images -o page.md
 
+# Extract images (inline base64 + remote) to a local images/ folder
+web-capture https://example.com --extract-images -o page.md
+
 # Custom images directory
-web-capture https://example.com --images-dir assets -o page.md
+web-capture https://example.com --extract-images --images-dir assets -o page.md
 
 # Disable specific features
 web-capture https://example.com --no-extract-latex --no-post-process -o page.md
@@ -245,32 +251,33 @@ web-capture --serve [--port <port>]
 web-capture <url> [options]
 ```
 
-| Option                      | Short | Description                                    | Default                             |
-| --------------------------- | ----- | ---------------------------------------------- | ----------------------------------- |
-| `--format`                  | `-f`  | Output format (see below)                      | `markdown`                          |
-| `--output`                  | `-o`  | Output file path. Use `-o -` for stdout        | auto-derived from URL               |
-| `--data-dir`                |       | Base directory for auto-derived output paths   | `./data/web-capture`                |
-| `--engine`                  | `-e`  | Browser engine: `puppeteer`, `playwright`      | `puppeteer` (or BROWSER_ENGINE env) |
-| `--theme`                   | `-t`  | Color scheme: `light`, `dark`, `no-preference` | browser default                     |
-| `--width`                   |       | Viewport width in pixels                       | 1280                                |
-| `--height`                  |       | Viewport height in pixels                      | 800                                 |
-| `--quality`                 |       | JPEG quality 0-100                             | 80                                  |
-| `--fullPage`                |       | Capture full scrollable page                   | false                               |
-| `--embed-images`            |       | Keep images as inline base64 data URIs         | false                               |
-| `--no-extract-images`       |       | Alias for `--embed-images`                     | false                               |
-| `--keep-original-links`     |       | Keep original remote URLs, strip base64        | false                               |
-| `--images-dir`              |       | Subdirectory name for extracted images         | `images`                            |
-| `--archive`                 |       | Create archive: `zip`, `7z`, `tar.gz`, `tar`   | -                                   |
-| `--document-format`         |       | Document format in archive: `markdown`, `html` | `markdown`                          |
-| `--localImages`             |       | Download images locally in archive mode        | true                                |
-| `--extract-latex`           |       | Extract LaTeX formulas                         | true                                |
-| `--no-extract-latex`        |       | Disable LaTeX extraction                       | -                                   |
-| `--extract-metadata`        |       | Extract article metadata                       | true                                |
-| `--no-extract-metadata`     |       | Disable metadata extraction                    | -                                   |
-| `--post-process`            |       | Apply post-processing                          | true                                |
-| `--no-post-process`         |       | Disable post-processing                        | -                                   |
-| `--detect-code-language`    |       | Detect code block languages                    | true                                |
-| `--no-detect-code-language` |       | Disable code language detection                | -                                   |
+| Option                      | Short | Description                                       | Default                             |
+| --------------------------- | ----- | ------------------------------------------------- | ----------------------------------- |
+| `--format`                  | `-f`  | Output format (see below)                         | `markdown`                          |
+| `--output`                  | `-o`  | Output file path. Use `-o -` for stdout           | auto-derived from URL               |
+| `--data-dir`                |       | Base directory for auto-derived output paths      | `./data/web-capture`                |
+| `--engine`                  | `-e`  | Browser engine: `puppeteer`, `playwright`         | `puppeteer` (or BROWSER_ENGINE env) |
+| `--theme`                   | `-t`  | Color scheme: `light`, `dark`, `no-preference`    | browser default                     |
+| `--width`                   |       | Viewport width in pixels                          | 1280                                |
+| `--height`                  |       | Viewport height in pixels                         | 800                                 |
+| `--quality`                 |       | JPEG quality 0-100                                | 80                                  |
+| `--fullPage`                |       | Capture full scrollable page                      | false                               |
+| `--embed-images`            |       | Keep images inline as base64 (self-contained)     | false                               |
+| `--no-extract-images`       |       | Alias for `--embed-images`                        | false                               |
+| `--extract-images[=DIR]`    |       | Extract images to `DIR/images/` + download remote | -                                   |
+| `--keep-original-links`     |       | Keep remote URLs as direct links (the default)    | false                               |
+| `--images-dir`              |       | Subdirectory name for extracted images            | `images`                            |
+| `--archive`                 |       | Create archive: `zip`, `7z`, `tar.gz`, `tar`      | -                                   |
+| `--document-format`         |       | Document format in archive: `markdown`, `html`    | `markdown`                          |
+| `--localImages`             |       | Download images locally in archive mode           | true                                |
+| `--extract-latex`           |       | Extract LaTeX formulas                            | true                                |
+| `--no-extract-latex`        |       | Disable LaTeX extraction                          | -                                   |
+| `--extract-metadata`        |       | Extract article metadata                          | true                                |
+| `--no-extract-metadata`     |       | Disable metadata extraction                       | -                                   |
+| `--post-process`            |       | Apply post-processing                             | true                                |
+| `--no-post-process`         |       | Disable post-processing                           | -                                   |
+| `--detect-code-language`    |       | Detect code block languages                       | true                                |
+| `--no-detect-code-language` |       | Disable code language detection                   | -                                   |
 
 **Supported formats:**
 

package/bin/web-capture.js

@@ -154,7 +154,7 @@ const config = makeConfig({
       .option('embedImages', {
         type: 'boolean',
         description:
-          'Keep images as inline base64 data URIs instead of extracting to files (default: false). Use --embed-images to enable.',
+          'Keep images inline as base64 data URIs, producing a single self-contained file (default: false). By default markdown keeps remote images as direct links; use --extract-images to save them as local files.',
         default: getenv('WEB_CAPTURE_EMBED_IMAGES', false),
       })
       .option('imagesDir', {
@@ -163,6 +163,14 @@ const config = makeConfig({
           'Directory name for extracted images, relative to output file (default: images)',
         default: getenv('WEB_CAPTURE_IMAGES_DIR', 'images'),
       })
+      .option('extractImages', {
+        type: 'string',
+        description:
+          'Extract images to local files under <dir>/images/ and rewrite the ' +
+          'markdown to reference them. Pass a directory, or use the flag with ' +
+          'no value to extract next to the output file. Downloads remote images too.',
+        default: getenv('WEB_CAPTURE_EXTRACT_IMAGES', undefined),
+      })
       .option('dataDir', {
         type: 'string',
         description:
@@ -183,8 +191,9 @@ const config = makeConfig({
       .option('keepOriginalLinks', {
         type: 'boolean',
         description:
-          'Keep original remote image URLs instead of downloading or extracting. ' +
-          'Base64 data URIs are stripped (no original URL to restore).',
+          'Keep remote image URLs as direct links — the default markdown ' +
+          'behavior, kept as an explicit alias for back-compat. Base64 data ' +
+          'URIs are stripped (no original URL to restore).',
         default: getenv('WEB_CAPTURE_KEEP_ORIGINAL_LINKS', false),
       })
       .option('dualTheme', {
@@ -337,6 +346,123 @@ function deriveOutputPath(absoluteUrl, ext, dataDir) {
   return path.join(dir, `document.${ext}`);
 }
 
+/**
+ * Resolve the image mode for a markdown output destined for `outputDir`,
+ * mirroring the Rust CLI precedence: --embed-images > --extract-images >
+ * default (keep remote links, strip inline base64). See issue #112.
+ *
+ * @param {Object} options - Parsed CLI options
+ * @param {string} outputDir - Directory the markdown file is written to
+ * @returns {{mode: 'embed'|'extract'|'default', dir?: string, subdir: string}}
+ */
+function resolveImageMode(options, outputDir) {
+  const subdir = options.imagesDir || 'images';
+  if (options.embedImages) {
+    return { mode: 'embed', subdir };
+  }
+  const extract = options.extractImages;
+  // `--extract-images` with no value arrives as '' (or true); fall back to the
+  // output directory in that case, otherwise use the provided directory.
+  if (extract !== undefined && extract !== false && extract !== null) {
+    const dir = extract === '' || extract === true ? outputDir : extract;
+    return { mode: 'extract', dir, subdir };
+  }
+  return { mode: 'default', subdir };
+}
+
+/**
+ * Download remote images that an `extract` mode localized, writing them under
+ * `imagesPath`. On any failure the original remote URL is restored so the
+ * markdown never points at a missing local file. Mirrors the Rust helper.
+ *
+ * @param {string} markdown - Markdown with localized remote references
+ * @param {Array<{url: string, filename: string}>} pending - Remote images to fetch
+ * @param {string} imagesPath - Absolute directory to write images into
+ * @param {string} subdir - Images subdirectory name (for the local reference)
+ * @returns {Promise<string>} The (possibly URL-restored) markdown
+ */
+async function downloadPendingRemote(markdown, pending, imagesPath, subdir) {
+  let result = markdown;
+  let downloaded = 0;
+  for (const img of pending) {
+    const localRef = `${subdir}/${img.filename}`;
+    let buffer = null;
+    try {
+      const resp = await fetch(img.url);
+      if (resp.ok) {
+        buffer = Buffer.from(await resp.arrayBuffer());
+      }
+    } catch {
+      buffer = null;
+    }
+    let saved = false;
+    if (buffer) {
+      try {
+        fs.mkdirSync(imagesPath, { recursive: true });
+        fs.writeFileSync(path.join(imagesPath, img.filename), buffer);
+        saved = true;
+      } catch {
+        saved = false;
+      }
+    }
+    if (saved) {
+      downloaded++;
+    } else {
+      // Restore the original URL so the reference is not broken.
+      result = result.split(localRef).join(img.url);
+    }
+  }
+  if (downloaded > 0) {
+    console.error(`Downloaded ${downloaded} remote image(s) to ${subdir}/`);
+  }
+  return result;
+}
+
+/**
+ * Apply the resolved image mode to markdown destined for `outputPath`,
+ * downloading any remote images an extract mode localized. The single
+ * image-handling chokepoint for the JS CLI — every markdown output path routes
+ * through this so flags behave uniformly regardless of capture method (#112).
+ *
+ * @param {string} markdown - Markdown content
+ * @param {Object} options - Parsed CLI options
+ * @param {string} outputPath - File the markdown will be written to
+ * @param {string} label - Human label for log messages
+ * @returns {Promise<string>} The rewritten markdown
+ */
+async function processOutputMarkdown(markdown, options, outputPath, label) {
+  const { applyImageMode } = await import('../src/extract-images.js');
+  const outputDir = path.dirname(outputPath);
+  const resolved = resolveImageMode(options, outputDir);
+  const result = await applyImageMode(markdown, {
+    mode: resolved.mode,
+    dir: resolved.dir,
+    subdir: resolved.subdir,
+  });
+  let md = result.markdown;
+  if (result.extracted > 0) {
+    console.error(
+      `Extracted ${result.extracted} images to ${resolved.subdir}/ (${label})`
+    );
+  }
+  if (result.stripped > 0) {
+    console.error(
+      `Stripped ${result.stripped} inline base64 image(s) (${label}); ` +
+        'use --extract-images to save files or --embed-images to keep them inline'
+    );
+  }
+  if (resolved.mode === 'extract' && result.pendingRemote.length > 0) {
+    const imagesPath = path.resolve(resolved.dir, resolved.subdir);
+    md = await downloadPendingRemote(
+      md,
+      result.pendingRemote,
+      imagesPath,
+      resolved.subdir
+    );
+  }
+  return md;
+}
+
 function archiveExtension(archiveFormat) {
   if (archiveFormat === 'tar.gz' || archiveFormat === 'gz') {
     return 'tar.gz';
@@ -426,7 +552,8 @@ async function captureUrl(url, options) {
     // localImages is used by archive format
     // eslint-disable-next-line no-unused-vars
     localImages,
-    embedImages,
+    // imagesDir/embedImages/extractImages are read via `options` in the image
+    // mode chokepoint (resolveImageMode); destructured only for documentation.
     // eslint-disable-next-line no-unused-vars
     imagesDir,
     dataDir,
@@ -462,7 +589,6 @@ async function captureUrl(url, options) {
     captureGoogleDocWithBrowserOrFallback,
     selectGoogleDocsCaptureMethod,
   } = await import('../src/gdocs.js');
-  const { stripBase64Images } = await import('../src/extract-images.js');
 
   const normalizedFormat = format.toLowerCase();
   log.debug(() => ({
@@ -649,8 +775,6 @@ async function captureUrl(url, options) {
       }
     } else {
       try {
-        const { extractAndSaveImages } =
-          await import('../src/extract-images.js');
         if (normalizedFormat === 'archive' || normalizedFormat === 'zip') {
           const { fetchGoogleDocAsArchive } = await import('../src/gdocs.js');
           const { default: archiver } = await import('archiver');
@@ -721,36 +845,20 @@ async function captureUrl(url, options) {
             apiToken,
             log,
           });
-          let { markdown } = result;
+          const { markdown } = result;
           const output =
             explicitOutput === '-'
               ? null
               : explicitOutput || deriveOutputPath(absoluteUrl, 'md', dataDir);
           if (output) {
-            if (embedImages) {
-              // Keep base64 data URIs inline
-            } else if (keepOriginalLinks) {
-              const strip = stripBase64Images(markdown);
-              if (strip.stripped > 0) {
-                markdown = strip.markdown;
-                console.error(
-                  `Stripped ${strip.stripped} base64 images (keeping original links)`
-                );
-              }
-            } else {
-              const outputDir = path.dirname(output);
-              const extracted = extractAndSaveImages(markdown, outputDir, {
-                imagesDir: options.imagesDir || 'images',
-              });
-              if (extracted.extracted > 0) {
-                markdown = extracted.markdown;
-                console.error(
-                  `Extracted ${extracted.extracted} images to ${options.imagesDir || 'images'}/`
-                );
-              }
-            }
+            const finalMarkdown = await processOutputMarkdown(
+              markdown,
+              options,
+              output,
+              'Google Doc Markdown'
+            );
             fs.mkdirSync(path.dirname(output), { recursive: true });
-            fs.writeFileSync(output, markdown, 'utf-8');
+            fs.writeFileSync(output, finalMarkdown, 'utf-8');
             console.error(`Google Doc Markdown saved to: ${output}`);
           } else {
             process.stdout.write(markdown);
@@ -999,7 +1107,6 @@ async function captureUrl(url, options) {
       // Markdown format — enhanced conversion is now the default
       const html = await fetchHtml(absoluteUrl);
       const { convertHtmlToMarkdownEnhanced } = await import('../src/lib.js');
-      const { extractAndSaveImages } = await import('../src/extract-images.js');
       const result = convertHtmlToMarkdownEnhanced(html, absoluteUrl, {
         extractLatex: options.extractLatex,
         extractMetadata: options.extractMetadata,
@@ -1008,40 +1115,21 @@ async function captureUrl(url, options) {
         contentSelector: options.contentSelector,
         bodySelector: options.bodySelector,
       });
-      let markdown = result.markdown;
+      const markdown = result.markdown;
 
       const output =
         explicitOutput === '-'
           ? null
           : explicitOutput || deriveOutputPath(absoluteUrl, 'md', dataDir);
       if (output) {
-        if (embedImages) {
-          // Keep base64 data URIs inline
-        } else if (keepOriginalLinks) {
-          const strip = stripBase64Images(markdown);
-          if (strip.stripped > 0) {
-            markdown = strip.markdown;
-            console.error(
-              `Stripped ${strip.stripped} base64 images (keeping original links)`
-            );
-          }
-        } else {
-          const outputDir = path.dirname(output);
-          const extracted = extractAndSaveImages(markdown, outputDir, {
-            imagesDir: options.imagesDir || 'images',
-          });
-          if (extracted.extracted > 0) {
-            markdown = extracted.markdown;
-            console.error(
-              `Extracted ${extracted.extracted} images to ${options.imagesDir || 'images'}/`
-            );
-          }
-        }
-      }
-
-      if (output) {
+        const finalMarkdown = await processOutputMarkdown(
+          markdown,
+          options,
+          output,
+          'Markdown'
+        );
         fs.mkdirSync(path.dirname(output), { recursive: true });
-        fs.writeFileSync(output, markdown, 'utf-8');
+        fs.writeFileSync(output, finalMarkdown, 'utf-8');
         console.error(`Markdown saved to: ${output}`);
       } else {
         process.stdout.write(markdown);
@@ -1192,6 +1280,7 @@ async function main() {
       dualTheme: config.dualTheme,
       apiToken: config.apiToken,
       embedImages: config.embedImages,
+      extractImages: config.extractImages,
       imagesDir: config.imagesDir,
       dataDir: config.dataDir,
       archiveFormat: config.archiveFormat,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/web-capture",
-  "version": "1.7.26",
+  "version": "1.8.0",
   "description": "CLI and microservice to render web pages as HTML, Markdown, or PNG",
   "main": "src/index.js",
   "bin": {
@@ -65,7 +65,8 @@
     "markdown-it": "^14.1.1",
     "nock": "^13.5.4",
     "prettier": "^3.6.2",
-    "supertest": "^6.3.4"
+    "supertest": "^6.3.4",
+    "unzipper": "^0.12.3"
   },
   "type": "module",
   "keywords": [

package/src/archive.js

@@ -170,14 +170,17 @@ export async function archiveHandler(req, res) {
       }
 
       if (!embedImages && !keepOriginalLinks) {
-        const b64 = extractBase64ToBuffers(markdown, 'images');
-        markdown = b64.markdown;
-        for (const img of b64.images) {
-          archive.append(img.buffer, { name: `images/${img.filename}` });
-        }
+        appendMarkdownAndImages(archive, markdown);
+      } else {
+        archive.append(markdown, { name: 'document.md' });
       }
 
-      archive.append(markdown, { name: 'document.md' });
+      // document.html — the source the markdown was derived from, for
+      // reference only, so the default archive layout (document.md +
+      // document.html + images/) is identical across capture paths (issue #113).
+      archive.append(prettyPrintHtml(convertRelativeUrls(html, absoluteUrl)), {
+        name: 'document.html',
+      });
     }
 
     // Download and add images if local mode
@@ -207,6 +210,57 @@ export async function archiveHandler(req, res) {
   }
 }
 
+/**
+ * Extract base64 images from `markdown` into the archive's `images/` folder and
+ * append the rewritten markdown as `document.md`. Shared by the archive
+ * endpoint and {@link buildArchiveFromHtml} so the default layout stays
+ * identical across capture paths.
+ *
+ * @param {import('archiver').Archiver} archive - The archive being built
+ * @param {string} markdown - Markdown content (may contain base64 data URIs)
+ */
+function appendMarkdownAndImages(archive, markdown) {
+  const { markdown: rewritten, images } = extractBase64ToBuffers(
+    markdown,
+    'images'
+  );
+  for (const img of images) {
+    archive.append(img.buffer, { name: `images/${img.filename}` });
+  }
+  archive.append(rewritten, { name: 'document.md' });
+}
+
+/**
+ * Build a self-contained ZIP archive (as a Buffer) from raw HTML, matching the
+ * default `--format archive` layout contract (issue #113):
+ *
+ *   - `document.md`   — markdown referencing images by relative `images/` path
+ *   - `document.html` — the source HTML the markdown was derived from (reference)
+ *   - `images/`       — every inline base64 image as a separate file
+ *
+ * @param {string} html - Source HTML to convert
+ * @param {string} baseUrl - Base URL for resolving relative links
+ * @returns {Promise<Buffer>} the finalized ZIP archive bytes
+ */
+export async function buildArchiveFromHtml(html, baseUrl) {
+  const archive = archiver('zip', { zlib: { level: 9 } });
+  const chunks = [];
+  archive.on('data', (chunk) => chunks.push(chunk));
+  const finished = new Promise((resolve, reject) => {
+    archive.on('end', resolve);
+    archive.on('error', reject);
+  });
+
+  appendMarkdownAndImages(archive, convertHtmlToMarkdown(html, baseUrl));
+  archive.append(prettyPrintHtml(convertRelativeUrls(html, baseUrl)), {
+    name: 'document.html',
+  });
+
+  await archive.finalize();
+  await finished;
+  return Buffer.concat(chunks);
+}
+
 function guessImageExtension(url) {
   const pathname = new URL(url).pathname.toLowerCase();
   if (pathname.endsWith('.jpg') || pathname.endsWith('.jpeg')) {

package/src/extract-images.js

@@ -128,3 +128,93 @@ export function stripBase64Images(markdown) {
 export function hasBase64Images(markdown) {
   return BASE64_IMAGE_REGEX.test(markdown);
 }
+
+// Matches a markdown image whose source is a remote http(s) URL. A trailing
+// markdown title attribute (e.g. `![](url "caption")`) is matched but excluded
+// from the captured URL.
+const REMOTE_IMAGE_REGEX =
+  /!\[([^\]]*)\]\((https?:\/\/[^)\s]+)(?:\s+"[^"]*")?\)/g;
+
+function remoteImageExtension(url) {
+  const cleaned = url.split(/[?#]/)[0];
+  const ext = (cleaned.split('.').pop() || '').toLowerCase();
+  if (ext === 'jpg' || ext === 'jpeg') {
+    return 'jpg';
+  }
+  if (['gif', 'webp', 'svg'].includes(ext)) {
+    return ext;
+  }
+  return 'png';
+}
+
+/**
+ * Apply an image mode to markdown — the single image-handling chokepoint.
+ *
+ * Every CLI/server capture path routes through this function so the same flag
+ * produces the same result regardless of capture method (browser vs API). See
+ * issue #112.
+ *
+ * Modes:
+ *  - `'default'`: keep remote URLs as direct links; strip inline base64 data
+ *    URIs (no remote URL to restore) to a visible placeholder. No `images/`
+ *    folder, no silently-kept multi-megabyte base64 blob.
+ *  - `'embed'`: keep base64 inline (single self-contained file).
+ *  - `'extract'`: extract base64 to files under `dir/subdir` and rewrite remote
+ *    references to the same local `subdir/` paths. The remote bytes are
+ *    downloaded by the caller — see `pendingRemote` in the result.
+ *
+ * @param {string} markdown - Markdown content
+ * @param {Object} [options]
+ * @param {'default'|'embed'|'extract'} [options.mode='default']
+ * @param {string} [options.dir] - Output directory (required for 'extract')
+ * @param {string} [options.subdir='images'] - Images subdirectory name
+ * @returns {Promise<{markdown: string, extracted: number, stripped: number, pendingRemote: Array<{url: string, filename: string}>}>}
+ */
+// Async by contract: this is the single chokepoint every capture path awaits,
+// and remote localization is fulfilled asynchronously by the caller. The body
+// itself is currently synchronous.
+// eslint-disable-next-line require-await
+export async function applyImageMode(markdown, options = {}) {
+  const { mode = 'default', dir, subdir = 'images' } = options;
+
+  if (mode === 'embed') {
+    return { markdown, extracted: 0, stripped: 0, pendingRemote: [] };
+  }
+
+  if (mode === 'extract') {
+    if (!dir) {
+      throw new Error("applyImageMode: 'extract' mode requires an output dir");
+    }
+    // 1. Extract inline base64 images to files.
+    const extracted = extractAndSaveImages(markdown, dir, {
+      imagesDir: subdir,
+    });
+    // 2. Plan localization of remote image references to the same folder.
+    const pendingRemote = [];
+    let index = 0;
+    const localized = extracted.markdown.replace(
+      REMOTE_IMAGE_REGEX,
+      (_match, altText, url) => {
+        index++;
+        const filename = `image-${String(index).padStart(2, '0')}.${remoteImageExtension(url)}`;
+        pendingRemote.push({ url, filename });
+        return `![${altText}](${subdir}/${filename})`;
+      }
+    );
+    return {
+      markdown: localized,
+      extracted: extracted.extracted,
+      stripped: 0,
+      pendingRemote,
+    };
+  }
+
+  // 'default'
+  const strip = stripBase64Images(markdown);
+  return {
+    markdown: strip.markdown,
+    extracted: 0,
+    stripped: strip.stripped,
+    pendingRemote: [],
+  };
+}

package/src/markdown.js

@@ -1,5 +1,5 @@
 import { fetchHtml, convertHtmlToMarkdownEnhanced } from './lib.js';
-import { stripBase64Images } from './extract-images.js';
+import { applyImageMode } from './extract-images.js';
 
 export async function markdownHandler(req, res) {
   const url = req.query.url;
@@ -9,15 +9,17 @@ export async function markdownHandler(req, res) {
   const embedImages = req.query.embedImages === 'true';
   try {
     const html = await fetchHtml(url);
-    let { markdown } = convertHtmlToMarkdownEnhanced(html, url, {
+    const { markdown } = convertHtmlToMarkdownEnhanced(html, url, {
       contentSelector: req.query.contentSelector,
       bodySelector: req.query.bodySelector,
     });
-    if (!embedImages) {
-      const strip = stripBase64Images(markdown);
-      markdown = strip.markdown;
-    }
-    res.type('text/markdown').send(markdown);
+    // Route through the single image-mode chokepoint so the server honors the
+    // same contract as the CLI: default keeps remote links and strips inline
+    // base64; ?embedImages=true keeps base64 inline. See issue #112.
+    const result = await applyImageMode(markdown, {
+      mode: embedImages ? 'embed' : 'default',
+    });
+    res.type('text/markdown').send(result.markdown);
   } catch (err) {
     console.error(err);
     res.status(500).send('Error converting to Markdown');

package/tests/integration/api-endpoints.test.js

@@ -9,6 +9,7 @@
 import { jest } from '@jest/globals';
 import request from 'supertest';
 import nock from 'nock';
+import unzipper from 'unzipper';
 import { app } from '../../src/index.js';
 
 jest.setTimeout(60000);
@@ -95,6 +96,14 @@ describe('API Endpoint Tests', () => {
       // ZIP signature: PK (0x50 0x4B)
       expect(res.body[0]).toBe(0x50);
       expect(res.body[1]).toBe(0x4b);
+
+      // Default archive layout contract (issue #113): the markdown archive must
+      // bundle document.md AND document.html for reference.
+      const dir = await unzipper.Open.buffer(res.body);
+      const names = dir.files.map((f) => f.path);
+      expect(names).toEqual(
+        expect.arrayContaining(['document.md', 'document.html'])
+      );
     });
 
     it('returns a ZIP archive with HTML format', async () => {

package/tests/integration/archive-default-layout.test.js

@@ -0,0 +1,37 @@
+/**
+ * Pin the default `--format archive` layout contract (issue #113):
+ * the zip contains exactly `document.md` + `document.html` + `images/`.
+ */
+import unzipper from 'unzipper';
+import { buildArchiveFromHtml } from '../../src/archive.js';
+
+const TINY_PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==';
+const FIXTURE_HTML = `<!doctype html><html><body>
+  <h1>Hi</h1><p>Para 1.</p>
+  <p><img alt="" src="data:image/png;base64,${TINY_PNG}"></p>
+  <p>Para 2.</p>
+</body></html>`;
+
+it('default archive contains document.md, document.html, and images/ folder', async () => {
+  const buf = await buildArchiveFromHtml(
+    FIXTURE_HTML,
+    'https://example.invalid/'
+  );
+  const dir = await unzipper.Open.buffer(buf);
+  const names = dir.files.map((f) => f.path);
+
+  expect(names).toEqual(
+    expect.arrayContaining(['document.md', 'document.html'])
+  );
+  expect(names.some((n) => n.startsWith('images/'))).toBe(true);
+
+  const mdEntry = dir.files.find((f) => f.path === 'document.md');
+  const md = (await mdEntry.buffer()).toString();
+  expect(md).toMatch(/images\//);
+  expect(md).not.toMatch(/data:image/);
+
+  const htmlEntry = dir.files.find((f) => f.path === 'document.html');
+  const html = (await htmlEntry.buffer()).toString();
+  expect(html).toMatch(/<h1>/);
+});

package/tests/unit/image-mode-defaults.test.js

@@ -0,0 +1,54 @@
+import { applyImageMode } from '../../src/extract-images.js';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const TINY_PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==';
+const REMOTE = `Hi.\n\n![](https://example.invalid/foo.png)\n\nBye.\n`;
+const BASE64 = `Hi.\n\n![](data:image/png;base64,${TINY_PNG})\n\nBye.\n`;
+
+describe('image-mode contract', () => {
+  let tmp;
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'imode-'));
+  });
+  afterEach(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  it('default mode keeps remote URLs', async () => {
+    const r = await applyImageMode(REMOTE, { mode: 'default' });
+    expect(r.markdown).toContain('https://example.invalid/foo.png');
+    expect(r.markdown).not.toMatch(/images\//);
+    expect(r.markdown).not.toMatch(/data:image/);
+  });
+
+  it('--extract-images writes files', async () => {
+    const r = await applyImageMode(BASE64, {
+      mode: 'extract',
+      dir: tmp,
+      subdir: 'images',
+    });
+    expect(r.markdown).toMatch(/images\/image-/);
+    expect(fs.readdirSync(path.join(tmp, 'images'))).toHaveLength(1);
+  });
+
+  it('--embed-images keeps base64', async () => {
+    const r = await applyImageMode(BASE64, { mode: 'embed' });
+    expect(r.markdown).toContain('data:image');
+  });
+
+  it('flags have observable effect on every input', async () => {
+    for (const src of [REMOTE, BASE64]) {
+      const a = await applyImageMode(src, { mode: 'default' });
+      const b = await applyImageMode(src, { mode: 'embed' });
+      const c = await applyImageMode(src, {
+        mode: 'extract',
+        dir: tmp,
+        subdir: 'images',
+      });
+      expect(
+        new Set([a.markdown, b.markdown, c.markdown]).size
+      ).toBeGreaterThan(1);
+    }
+  });
+});